<HTML><HEAD><TITLE>split_string(+String, +SepChars, +PadChars, -SubStrings)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Strings and Atoms</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>split_string(+String, +SepChars, +PadChars, -SubStrings)</H1>
Decompose String into SubStrings according to separators SepChars and
padding characters PadChars.


<DL>
<DT><EM>String</EM></DT>
<DD>A string.
</DD>
<DT><EM>SepChars</EM></DT>
<DD>A string.
</DD>
<DT><EM>PadChars</EM></DT>
<DD>A string.
</DD>
<DT><EM>SubStrings</EM></DT>
<DD>A variable or list.
</DD>
</DL>
<H2>Description</H2>
   The string String is decomposed into sub-strings which are returned
   as a list of strings SubStrings.  Every character occurring in
   SepChars is considered a separator, and every character occurring
   in PadChars is considered a padding character.

<P>
   The string String is split at the separators, and any padding
   characters around the resulting sub-strings are removed. Neither
   the separators nor the padding characters occur in SubStrings.

<P>
   Characters that occur both in SepChars and PadChars are considered
   separators, but such that a sequence of them is considered to be
   only one separator. Moreover, when they occur at the beginning or
   end of the string, they are ignored, ie. treated like padding.

<P>
   The predicate can also be used to trim leading and trailing padding
   from a string by giving an empty separator string.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>split_string(+, +, +, -) is det
</UL>
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>String, SepChars or PadChars is not instantiated.
<DT><EM>(5) type error </EM>
<DD>String, SepChars or PadChars is not a string.
<DT><EM>(5) type error </EM>
<DD>List is neither an string nor a variable.
</DL>
<H2>Examples</H2>
<PRE>
     % split at every /
     [eclipse]: split_string("/usr/local/eclipse", "/", "", L).
     L = ["", "usr", "local", "eclipse"]
     yes.

     % split at every sequence of /
     [eclipse]: split_string("/usr/local//eclipse/", "/", "/", L).
     L = ["usr", "local", "eclipse"]
     yes.

     % split and strip padding
     [eclipse 4]: split_string(" comma, separated , data items ",
                                                        ",", " \t", L).
     L = ["comma", "separated", "data items"]
     yes.

     % just strip padding
     [eclipse]: split_string("   Hello world...", "", " .", L).
     L = ["Hello world"]
     yes.




</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/stratom/atom_string-2.html">atom_string / 2</A>, <A HREF="../../kernel/stratom/concat_string-2.html">concat_string / 2</A>, <A HREF="../../kernel/stratom/join_string-3.html">join_string / 3</A>, <A HREF="../../kernel/stratom/number_string-2.html">number_string / 2</A>, <A HREF="../../kernel/iochar/read_string-3.html">read_string / 3</A>, <A HREF="../../kernel/iochar/read_string-4.html">read_string / 4</A>, <A HREF="../../kernel/iochar/read_token-2.html">read_token / 2</A>, <A HREF="../../kernel/iochar/read_token-3.html">read_token / 3</A>, <A HREF="../../kernel/termmanip/term_string-2.html">term_string / 2</A>, <A HREF="../../lib/regex/index.html">library(regex)</A>
</BODY></HTML>
